Skip to content

refactor: reorganize Plane AI documentation into structured sub-pages#273

Open
akhil-vamshi-konam wants to merge 5 commits into
masterfrom
chore-update-self-hosted-ai
Open

refactor: reorganize Plane AI documentation into structured sub-pages#273
akhil-vamshi-konam wants to merge 5 commits into
masterfrom
chore-update-self-hosted-ai

Conversation

@akhil-vamshi-konam
Copy link
Copy Markdown
Collaborator

@akhil-vamshi-konam akhil-vamshi-konam commented May 11, 2026

Description

Restructures the Plane AI self-hosting docs from a single monolithic page into a focused sub-page structure under /self-hosting/govern/plane-ai/.

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • Feature (non-breaking change which adds functionality)
  • Improvement (change that would cause existing functionality to not work as expected)
  • Code refactoring
  • Performance improvements
  • Documentation update

Screenshots and Media (if applicable)

Test Scenarios

References

Summary by CodeRabbit

  • Documentation
    • Reorganized Plane AI self-hosting docs and updated sidebar navigation into grouped sections.
    • Added Getting Started, Custom LLM, Semantic Search, and AWS OpenSearch embedding guides.
    • Updated environment-variable guidance and links for consistency; adjusted default token limit for custom LLM.
    • Replaced the previous unified Plane AI page with the new modular guides.

Review Change Stack

@vercel
Copy link
Copy Markdown

vercel Bot commented May 11, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
developer-docs Ready Ready Preview, Comment May 22, 2026 3:18pm

Request Review

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 11, 2026

📝 Walkthrough

Walkthrough

This PR reorganizes Plane AI self-hosting documentation from a single monolithic guide into modular, topic-focused pages. The VitePress sidebar is updated to create a parent "Plane AI" node with four child sections. A comprehensive getting-started guide covers prerequisites and step-by-step configuration; separate guides detail custom LLM setup and semantic search integration. Cross-document links are corrected to reference the new structure.

Changes

Plane AI Self-Hosting Documentation Restructure

Layer / File(s) Summary
Sidebar navigation restructuring
docs/.vitepress/config.mts
VitePress sidebar entry for Plane AI is changed from a single link to a collapsed parent containing child items for Get started, Custom LLM models, Semantic search, and AWS OpenSearch embedding.
Core Plane AI setup guide
docs/self-hosting/govern/plane-ai/getting-started.md
Comprehensive introduction and step-by-step setup documentation covering prerequisites (LLM API, OpenSearch, dedicated DB, main DB read access), supported models (OpenAI, Anthropic), environment configuration (databases, OpenSearch, LLM keys), PI deployment wiring, service enablement for Docker Compose and Kubernetes, restart procedures, and optional voice input and file-upload features.
Custom LLM model configuration
docs/self-hosting/govern/plane-ai/custom-llm.md
Documentation for integrating one custom LLM alongside built-in providers, distinguishing OpenAI-compatible endpoints from AWS Bedrock, providing environment variable configuration examples for both, including Bedrock IAM permissions and Kubernetes inference profile setup (IRSA/EKS pod identity).
Semantic search setup guide
docs/self-hosting/govern/plane-ai/semantic-search.md
Setup for semantic search as an optional BM25 alternative, including a catalog of supported embedding models with dimensions, two configuration paths (existing OpenSearch model or auto-deploy), restart procedures, commands to vectorize existing documents, and procedures for changing embedding models with guidance on dimension-mismatch implications.
Cross-reference updates
docs/self-hosting/govern/aws-opensearch-embedding.md, docs/self-hosting/govern/environment-variables.md
Links in AWS OpenSearch embedding and environment variables documentation are updated to point to the new getting-started and semantic-search pages instead of the consolidated Plane AI page; the PI custom LLM CUSTOM_LLM_MAX_TOKENS default was adjusted.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A warren of docs, now neatly organized—
Get started, search semantically, tune your LLMs to size.
One big file split into four, clear and wise,
Links corrected, structure crystallized. ✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately and specifically describes the main change: reorganizing Plane AI documentation into structured sub-pages, which is reflected in the removal of the monolithic docs/self-hosting/govern/plane-ai.md and creation of new sub-pages under /plane-ai/.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch chore-update-self-hosted-ai

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@akhil-vamshi-konam akhil-vamshi-konam marked this pull request as ready for review May 20, 2026 07:50
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 7

🧹 Nitpick comments (1)
docs/self-hosting/govern/plane-ai/getting-started.md (1)

50-50: 💤 Low value

Consider completing the sentence for clarity.

The phrase "Can be a read replica." is grammatically incomplete. While understandable in context, completing it would improve readability.

✏️ Suggested improvement
-- **`FOLLOWER_POSTGRES_URI`** — Read connection to the main Plane database. PI reads workspace data (issues, pages, projects) directly from here. Can be a read replica.
+- **`FOLLOWER_POSTGRES_URI`** — Read connection to the main Plane database. PI reads workspace data (issues, pages, projects) directly from here. This can be a read replica.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/self-hosting/govern/plane-ai/getting-started.md` at line 50, The
sentence describing FOLLOWER_POSTGRES_URI is incomplete; update the line for
**`FOLLOWER_POSTGRES_URI`** to finish the thought (e.g., "Can be a read replica
of the primary database.") so it reads as a full sentence and clearly explains
that this URI may point to a read replica used for read-only access to workspace
data.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/self-hosting/govern/plane-ai/custom-llm.md`:
- Line 95: The long documentation sentence "Plane AI activates inference profile
mode automatically when a profile ARN or ID is set and ambient AWS credentials
are present (`AWS_ROLE_ARN`, `AWS_WEB_IDENTITY_TOKEN_FILE`,
`AWS_CONTAINER_CREDENTIALS_FULL_URI`, or
`AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE`)." exceeds 120 characters; break it
into shorter lines (e.g., two sentences or a short paragraph) or convert the
credential list into a bulleted list so no line exceeds 120 characters, update
the surrounding text to keep meaning unchanged, and run Prettier to ensure the
formatting check passes.
- Line 17: The sentence "Use a model with at least 1 trillion parameters" is
inconsistent with the examples (llama-3.3-70b-versatile and llama3); update that
requirement to the correct minimum (e.g., "70+ billion parameters" or "1
billion+" as appropriate for Plane AI features) so the guidance matches the
examples, and edit the sentence in custom-llm.md accordingly (referencing the
exact string "Use a model with at least 1 trillion parameters" and the example
model names "llama-3.3-70b-versatile" and "llama3" to locate and verify
consistency).
- Line 13: The table row under the "OpenAI-compatible" cell is over the 120-char
Prettier limit; shorten or reformat that cell to pass CI by either truncating
the provider list (e.g., "OpenAI-compatible (Ollama, Groq, vLLM, LiteLLM, ...)")
or breaking the content into multiple table rows or a wrapped multiline cell so
the line length is ≤120; update the cell text that currently reads "Your model
is served via an OpenAI Chat Completions API (Ollama, Groq, vLLM, LiteLLM,
Cerebras, etc.)" accordingly.
- Line 88: Add a brief clarifying comment next to the CUSTOM_LLM_MODEL_KEY entry
to explain that this value is the simplified inference profile ID (used for
cross-Region system-defined Bedrock inference profiles) and intentionally
differs from the full foundation model ID used with standard credentials;
reference the symbol CUSTOM_LLM_MODEL_KEY and include an example of the full
format (e.g., anthropic.claude-3-5-sonnet-20241022-v2:0) vs the simplified ID
(claude-sonnet-4-6) so readers understand the distinction.

In `@docs/self-hosting/govern/plane-ai/getting-started.md`:
- Line 11: Remove the duplicate sentence "For an overview of what Plane AI can
do, see [Plane AI](https://docs.plane.so/ai/pi-chat)." so it appears only once
in the document; locate both occurrences of that exact string and delete one of
them (either the instance at the earlier position or the later one) to eliminate
redundancy.
- Around line 26-27: Update the listed model versions in the getting-started
docs to remove non-existent entries and replace them with the currently
available recommended versions: remove "GPT-5.2" and any mention of "Claude
Sonnet 4.5", and add OpenAI models "GPT-5.5", "GPT-5.4", "GPT-5.4-mini",
"GPT-5.4-nano" and Anthropic models "Claude Opus 4.7", "Claude Sonnet 4.6",
"Claude Haiku 4.5" where "GPT-5.2" and the old Sonnet entry appear so
configuration examples and defaults reference valid model IDs.

In `@docs/self-hosting/govern/plane-ai/semantic-search.md`:
- Line 32: The doc currently says a mismatch for OPENSEARCH_EMBEDDING_DIMENSION
"breaks indexing" but later notes it "breaks indexing silently"; make these
consistent by updating the earlier sentence that mentions
OPENSEARCH_EMBEDDING_DIMENSION so it reads that a mismatch "breaks indexing
silently" (or equivalent phrasing) and verify the later sentence uses the same
wording to avoid ambiguity.

---

Nitpick comments:
In `@docs/self-hosting/govern/plane-ai/getting-started.md`:
- Line 50: The sentence describing FOLLOWER_POSTGRES_URI is incomplete; update
the line for **`FOLLOWER_POSTGRES_URI`** to finish the thought (e.g., "Can be a
read replica of the primary database.") so it reads as a full sentence and
clearly explains that this URI may point to a read replica used for read-only
access to workspace data.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e1990a1a-0622-4690-ab6a-4449ffb83678

📥 Commits

Reviewing files that changed from the base of the PR and between 92279d1 and 23671a1.

📒 Files selected for processing (7)
  • docs/.vitepress/config.mts
  • docs/self-hosting/govern/aws-opensearch-embedding.md
  • docs/self-hosting/govern/environment-variables.md
  • docs/self-hosting/govern/plane-ai.md
  • docs/self-hosting/govern/plane-ai/custom-llm.md
  • docs/self-hosting/govern/plane-ai/getting-started.md
  • docs/self-hosting/govern/plane-ai/semantic-search.md
💤 Files with no reviewable changes (1)
  • docs/self-hosting/govern/plane-ai.md

Comment thread docs/self-hosting/govern/plane-ai/custom-llm.md
Comment thread docs/self-hosting/govern/plane-ai/custom-llm.md
Comment thread docs/self-hosting/govern/plane-ai/custom-llm.md
Comment thread docs/self-hosting/govern/plane-ai/custom-llm.md
Comment thread docs/self-hosting/govern/plane-ai/getting-started.md Outdated
Comment thread docs/self-hosting/govern/plane-ai/getting-started.md
Comment thread docs/self-hosting/govern/plane-ai/semantic-search.md
Comment thread docs/self-hosting/govern/plane-ai/custom-llm.md Outdated
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/self-hosting/govern/environment-variables.md`:
- Line 213: The docs show two different defaults for CUSTOM_LLM_MAX_TOKENS (one
entry lists 64000, another lists 128000); pick the correct canonical default and
update both occurrences so they match—specifically change the standalone
environment variable row describing CUSTOM_LLM_MAX_TOKENS and the Plane
Intelligence table entry that references CUSTOM_LLM_MAX_TOKENS to the same value
and wording (e.g., “Defaults to `64000`” or “Defaults to `128000`”) to eliminate
the conflict.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 51f2c0a8-11da-477c-aa90-edaf4bcaa088

📥 Commits

Reviewing files that changed from the base of the PR and between 23671a1 and 279d582.

📒 Files selected for processing (4)
  • docs/self-hosting/govern/environment-variables.md
  • docs/self-hosting/govern/plane-ai/custom-llm.md
  • docs/self-hosting/govern/plane-ai/getting-started.md
  • docs/self-hosting/govern/plane-ai/semantic-search.md
💤 Files with no reviewable changes (1)
  • docs/self-hosting/govern/plane-ai/getting-started.md
✅ Files skipped from review due to trivial changes (2)
  • docs/self-hosting/govern/plane-ai/custom-llm.md
  • docs/self-hosting/govern/plane-ai/semantic-search.md

| **CUSTOM_LLM_AWS_REGION** | AWS region for the Bedrock model (e.g. `us-east-1`). Required when `CUSTOM_LLM_PROVIDER=bedrock`. | Optional |
| **CUSTOM_LLM_NAME** | Display name for the custom model shown in the UI. Defaults to `Custom LLM`. | Optional |
| **CUSTOM_LLM_MAX_TOKENS** | Maximum token limit for the custom model. Defaults to `128000`. | Optional |
| **CUSTOM_LLM_MAX_TOKENS** | Maximum token limit for the custom model. Defaults to `64000`. | Optional |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Resolve conflicting defaults for CUSTOM_LLM_MAX_TOKENS in the same page.

Line 213 now documents the default as 64000, but the Plane Intelligence table still shows 128000 at Line 312. Please align both entries to avoid configuration confusion.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/self-hosting/govern/environment-variables.md` at line 213, The docs show
two different defaults for CUSTOM_LLM_MAX_TOKENS (one entry lists 64000, another
lists 128000); pick the correct canonical default and update both occurrences so
they match—specifically change the standalone environment variable row
describing CUSTOM_LLM_MAX_TOKENS and the Plane Intelligence table entry that
references CUSTOM_LLM_MAX_TOKENS to the same value and wording (e.g., “Defaults
to `64000`” or “Defaults to `128000`”) to eliminate the conflict.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants